---
title: Instala y configura Astro
description: 'Cómo instalar Astro y empezar a trabajar en un proyecto nuevo.'
i18nReady: true
---
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

El [comando CLI `create astro`](#instala-desde-el-asistente-cli) es la forma más rápida de crear un nuevo proyecto de Astro desde cero.
Te guiará a través de cada paso de la configuración de tu nuevo proyecto de Astro y te permitirá elegir entre diferentes plantillas de inicio oficiales.

O, puedes empezar tu proyecto [utilizando un tema existente o una plantilla de inicio](#usa-un-tema-o-una-plantilla-de-inicio).

Para instalar Astro manualmente, consulta nuestra [guía de instalación manual paso a paso](#configuración-manual).

:::tip[Previsualización online]
¿Prefieres probar Astro en tu navegador? Visita [astro.new](https://astro.new/) para explorar nuestras plantillas de inicio y crear un nuevo proyecto de Astro sin salir de tu navegador.
:::

## Prerrequisitos

- **Node.js** - `v18.17.1`, `v20.3.0` o superior. ( `v19` no es soportada.)
- **Editor de código** - Recomendamos [VS Code](https://code.visualstudio.com/) con nuestra [extensión oficial de Astro](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode).
- **Terminal** - Astro es usado a través de la interfaz de línea de comandos (CLI).


## Empezar un nuevo proyecto

### Instala desde el asistente CLI

<Steps>
1. Ejecuta el siguiente comando en tu terminal para iniciar el asistente de instalación:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # crea un nuevo proyecto con npm
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # crea un nuevo proyecto con pnpm
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # crea un nuevo proyecto con yarn
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>

    Puedes ejecutar `create astro` desde cualquier lugar de tu máquina, así que no es necesario crear una nueva carpeta vacía para tu proyecto antes de comenzar. Si aún no tienes una carpeta vacía para tu nuevo proyecto, el asistente te ayudará a crear una automáticamente.

    Si todo va bien, verás un mensaje de éxito seguido de siguientes pasos recomendados. Ahora que tu proyecto ha sido creado, puedes navegar utilizando `cd` a tu nueva carpeta para comenzar a usar Astro.

2. Si saltaste el paso `npm install` durante el asistente CLI, asegúrate de instalar tus dependencias antes de continuar.

3. Ahora puedes [iniciar el servidor de desarrollo de Astro](#iniciar-el-servidor-de-desarrollo-de-astro) y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!
</Steps>

### Usa un tema o una plantilla de inicio

También puedes empezar un nuevo proyecto de Astro basado en un [ejemplo oficial](https://github.com/withastro/astro/tree/main/examples) o en la rama `main` de cualquier repositorio de GitHub pasando un argumento `--template` al comando `create astro`.

<Steps>
1. Explora nuestro [escaparate de temas y plantillas de inicio](https://astro.build/themes/) donde puedes navegar por temas para blogs, portafolios, sitios de documentación, páginas landing y más. O, [busca en GitHub](https://github.com/search?o=desc&q=astro+starter&s=stars&type=Repositories) para encontrar aún más proyectos de inicio.

2. Ejecuta el siguiente comando en tu terminal, sustituyendo el nombre de la plantilla de inicio oficial de Astro, o el nombre de usuario de GitHub y el repositorio del tema que quieras usar:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # crea un nuevo proyecto con un ejemplo oficial
      npm create astro@latest -- --template <example-name>

      # crea un nuevo proyecto basado en la rama principal de un repositorio de GitHub
      npm create astro@latest -- --template <github-username>/<github-repo>
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # crea un nuevo proyecto con un ejemplo oficial
      pnpm create astro@latest --template <example-name>

      # crea un nuevo proyecto basado en la rama principal de un repositorio de GitHub
      pnpm create astro@latest --template <github-username>/<github-repo>
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # crea un nuevo proyecto con un ejemplo oficial
      yarn create astro --template <example-name>

      # crea un nuevo proyecto basado en la rama principal de un repositorio de GitHub
      yarn create astro --template <github-username>/<github-repo>
      ```
      </Fragment>
    </PackageManagerTabs>

    Por defecto, este comando usará la rama `main` del repositorio de la plantilla. Para usar un nombre de rama diferente, pásalo como parte del argumento `--template`: `<github-username>/<github-repo>#<branch>`.

3. Responde las preguntas y sigue las instrucciones del asistente CLI.

4. Ahora puedes [iniciar el servidor de desarrollo de Astro](#iniciar-el-servidor-de-desarrollo-de-astro) y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!
</Steps>

### Configuración manual

Esta guía te guiará a través de los pasos para instalar y configurar manualmente un nuevo proyecto de Astro.

Si prefieres no utilizar nuestra herramienta automática CLI `create astro`, puedes configurar tu proyecto siguiendo la guía que se detalla a continuación.

<Steps>
1. Crea una carpeta

    Crea una carpeta vacía con el nombre de tu proyecto y navega hacia ella.

    ```bash
    mkdir my-astro-project
    cd my-astro-project
    ```

    Ya en la carpeta, crea un archivo `package.json` para tu proyecto. Esto te ayudará a gestionar las dependencias del proyecto, incluyendo Astro. Si no estás familiarizado con este formato de archivo, ejecuta el siguiente comando para crear uno.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm init --yes
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm init
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn init --yes
      ```
      </Fragment>
    </PackageManagerTabs>



2. Instala Astro

    Primero, instala Astro dentro de tu proyecto.

    :::note[Important]
    Astro debe ser instalado localmente, no globalmente. Asegúrate de *no* ejecutar `npm install -g astro`, `pnpm add -g astro` o `yarn add global astro`.
    :::

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install astro
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add astro
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add astro
      ```
      </Fragment>
    </PackageManagerTabs>

    A continuación, reemplaza los scripts creados por defecto en el `package.json` por los siguientes:

    ```json title="package.json" del={2} ins={3-6}
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "start": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },
    ```

    Los scripts serán usados más adelante en la guía para iniciar y ejecutar diferentes comandos en Astro.

3. Crea tu primera página

    En tu editor de código, crea un nuevo archivo en el directorio `src/pages/index.astro`. Esta será tu primera página de Astro en el proyecto.

    Copia y pega el siguiente fragmento de código (incluyendo `---` guiones) en tu nuevo archivo:

    ```astro title="src/pages/index.astro"
    ---
    // ¡Bienvenido a Astro! Todo entre los guiones triples son los
    // "metadatos de tu componente". Nunca se ejecuta en el navegador.
    console.log('¡Esto se ejecuta en tu terminal y no en el navegador!');
    ---
    <!-- El código de abajo es "la plantilla de su componente". Es solo HTML
         con un poco de magia que te ayudará a crear la plantilla del componente. -->
    <html>
      <body>
        <h1>¡Hola Mundo!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>
    ```

4. Crea tu primer archivo estático

    Crea una carpeta `public` en la raíz de tu proyecto para almacenar todos los archivos estáticos. Astro incluirá estos archivos en la compilación final, así podrán ser referenciados de forma segura desde tus componentes.

    Crea un nuevo archivo en el directorio `public/robots.txt`. `robots.txt` es un archivo que informa a los robots de búsqueda, como Google, sobre cómo indexar tu página web.

    Copia y pega el siguiente fragmento de código:

    ```diff title="public/robots.txt"
    # Example: Permitir a todos los bots de búsqueda escanear e indexar el sitio web.
    # Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
    ```

5. Crea `astro.config.mjs`

    Astro es configurado usando el archivo `astro.config.mjs`. Este archivo es opcional si no necesitas configurar Astro, pero recomendamos crear uno ahora.

    Crea un archivo `astro.config.mjs` en la raíz del proyecto y copia el siguiente código dentro de él:

    ```js title="astro.config.mjs"
    import { defineConfig } from 'astro/config';

    // https://astro.build/config
    export default defineConfig({});
    ```

    Si deseas incluir [componentes de frameworks](/es/guides/framework-components/) como React, Svelte, etc.; o usar otras herramientas de desarrollo como Tailwind o Partytown en tu proyecto, lee nuestra [guía de integraciones](/es/guides/integrations-guide/).

    Lee nuestra guía de [configuración de API](/es/reference/configuration-reference/) para más información.

6. Agrega soporte para TypeScript

    TypeScript es configurado usando `tsconfig.json`. Aun si tú no escribes código en TypeScript, este archivo es importante para que herramientas como Astro y VS Code sepan cómo comprender tu proyecto. Algunas características (como importaciones de paquetes npm) no tienen un soporte completo en el editor sin el archivo `tsconfig.json`.

    Si pretendes escribir código en TypeScript, recomendamos usar las plantillas de Astro `strict` o `strictest`. Puedes ver y comparar las tres configuraciones de las plantillas en [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/).

    Crea un archivo `tsconfig.json` en la raíz del proyecto y copia el siguiente código dentro de él. (Puedes usar `base`, `strict` o `strictest` para tu maquetado de TypeScript):

    ```json title="tsconfig.json" "base"
    {
      "extends": "astro/tsconfigs/base"
    }
    ```

    Finalmente, crea un archivo `src/env.d.ts` para que TypeScript infiera los tipos disponibles en un proyecto de Astro.

    ```ts title="src/env.d.ts"
    /// <reference types="astro/client" />
    ```

    Lee nuestra [guía para configurar TypeScript](/es/guides/typescript/#setup) para más información.

7. Siguientes pasos

    Si has seguido las instrucciones anteriores, el proyecto debe lucir así:

    <FileTree>
    - node_modules/
    - public/
      - robots.txt
    - src/
      - pages/
        - index.astro
      - env.d.ts
    - astro.config.mjs
    - package-lock.json o `yarn.lock`, `pnpm-lock.yaml`, etc.
    - package.json
    - tsconfig.json
    </FileTree>

8. Ahora puedes [iniciar el servidor de desarrollo de Astro](#iniciar-el-servidor-de-desarrollo-de-astro) y ¡ver una vista previa en vivo de tu proyecto mientras lo construyes!

</Steps>


## Iniciar el servidor de desarrollo de Astro

    Astro posee un servidor de desarrollo que tiene todo lo que necesitas para desarrollar tu proyecto. El comando `astro dev` iniciará el servidor de desarrollo local para que veas tu nuevo proyecto en acción por primera vez.

    Cada plantilla de inicio posee un script preconfigurado que ejecutará `astro dev` por ti. Utiliza tu gestor de paquetes favorito para ejecutar este comando e iniciar el servidor de desarrollo de Astro.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm run dev
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm run dev
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn run dev
      ```
      </Fragment>
    </PackageManagerTabs>

Si todo va bien, Astro servirá tu proyecto en [http://localhost:4321](http://localhost:4321). ¡Visita ese enlace en tu navegador y verás tu nuevo sitio!

## Trabajando en modo desarrollo

Astro escuchará cualquier cambio en la carpeta `src/` y actualizará automáticamente tu proyecto. De esta forma, no será necesario reiniciar el servidor local durante el desarrollo. Siempre verás la versión más reciente de tu proyecto en tu navegador mientras el servidor de desarrollo esté en ejecución.

Cuando visualices tu sitio en el navegador, tendrás acceso a la [barra de herramientas de desarrollo de Astro](/es/guides/dev-toolbar/). A medida que construyas, te ayudará a inspeccionar tus [islas](/es/concepts/islands/), detectar problemas de accesibilidad y mucho más.

Si no es posible abrir el proyecto en el navegador, regresa a la terminal donde has ejecutado el comando `dev` y chequea si ha ocurrido algún error o si tu proyecto está siendo servido en una URL diferente a la mencionada anteriormente. Deberías ver un mensaje si ha ocurrido algún error, o si tu proyecto está siendo servido en una URL diferente a [http://localhost:4321/](http://localhost:4321/).

## Construye y previsualiza tu sitio

Para comprobar la versión de tu sitio que será creada en tiempo de compilación, detén el servidor de desarrollo (<kbd>Ctrl</kbd> + <kbd>C</kbd>) y ejecuta el comando de construcción apropiado para tu gestor de paquetes en la terminal:

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm run build
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm build
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn run build
      ```
      </Fragment>
    </PackageManagerTabs>

Astro creará una versión de tu sitio lista para ser desplegada en una carpeta separada (`dist/` por defecto) y visualizará el progreso en la terminal. Esto te alertará de cualquier error de compilación en tu proyecto antes de desplegarlo en producción. Si TypeScript está configurado en `strict` o `strictest`, el script `build` también comprobará tu proyecto en busca de errores de tipado.

Cuando la construcción finalice, ejecuta el comando `preview` (por ejemplo, `npm run preview`) en tu terminal y podrás ver la versión construida de tu sitio en el navegador.

Ten en cuenta que esta previsualización de tu código es como existía cuando se ejecutó por última vez el comando de construcción. Esto está pensado para darte una vista previa de cómo se verá tu sitio cuando sea [desplegado en la web](#despliega-tu-sitio). Cualquier cambio posterior que realices en tu código después de la construcción **no** se reflejará mientras previsualices tu sitio hasta que vuelvas a ejecutar el comando de construcción.

Utiliza (<kbd>Ctrl</kbd> + <kbd>C</kbd>) para salir de la previsualización y ejecutar otro comando en la terminal, como reiniciar el servidor de desarrollo para volver a [trabajar en modo desarrollo](#trabajando-en-modo-desarrollo) que se actualiza a medida que editas para mostrar una vista previa en vivo de tus cambios de código.

<ReadMore>Lee más acerca [del CLI de Astro](/es/reference/cli-reference/) y los comandos de terminal que usarás mientras desarrollas con Astro.</ReadMore>

## Despliega tu sitio

Puede que quieras [desplegar tu nuevo sitio inmediatamente](/es/guides/deploy/), antes de comenzar a añadir o cambiar mucho código. Esto es útil para publicar una versión mínima y funcional de tu sitio que puede ahorrarte tiempo y esfuerzo extra al solucionar problemas con tu despliegue más adelante.

## Siguientes pasos

¡Genial! ¡Ahora estás listo para empezar a construir con Astro! 🥳

Aquí te dejamos algunas sugerencias para explorar a continuación. Puedes leerlas en cualquier orden, ¡incluso puedes dejar de lado la documentación por un momento y comenzar a experimentar con el código base de tu nuevo proyecto de Astro! Siempre puedes volver aquí cuando tengas dudas o necesites ayuda.

### Explora las funcionalidades de Astro

<CardGrid>
  <LinkCard
    title="Estructura de proyecto"
    description="Aprende cómo estructurar un proyecto en Astro."
    href="/es/basics/project-structure/"
  />
  <LinkCard
    title="Agrega integraciones"
    description="Añade contenido a tu nuevo sitio con validaciones de los metadatos de los componentes y seguridad de tipos automática."
    href="/es/guides/integrations-guide/"
  />
    <LinkCard
    title="Agrega transiciones de vista"
    description="Crea transiciones y animaciones de página fluidas."
    href="/es/guides/view-transitions/"
  />
  <LinkCard
    title="Aprende sobre Islas"
    description="Lee acerca de la arquitectura de las Islas Astro."
    href="/es/concepts/islands/"
  />
</CardGrid>


### Configura tu entorno de desarrollo

<CardGrid>
  <LinkCard
    title="Configuración del editor de código"
    description="Configura tu editor de código para mejorar tu experiencia de desarrollo con Astro y desbloquear nuevas funcionalidades."
    href="/es/editor-setup/"
  />
   <LinkCard
    title="TypeScript"
    description="¡Configura el soporte TypeScript integrado de Astro para que sea tan estricto o flexible como lo desees!"
    href="/es/guides/typescript/"
  />
  <LinkCard
    title="Alias de importación"
    description="Crea accesos directos convenientes para tus importaciones de archivos."
    href="/es/guides/imports/#aliases"
  />
  <LinkCard
    title="Variables de entorno"
    description="Establece y usa variables de entorno en tu proyecto."
    href="/es/guides/environment-variables/"
  />
    <LinkCard
    title="Barra de herramientas de desarrollo"
    description="Explora las útiles funciones de la barra de herramientas de desarrollo."
    href="/es/guides/dev-toolbar/"
  />
</CardGrid>
